//
//  SFCAuthenticationProvider.h
//  SVNForCocoa
//
//  Created by Jeremy Pereira on 17/11/2013.
//  Copyright (c) 2013 Jeremy Pereira. All rights reserved.
//
/*!
 *    @brief Declarations associated with authentication providers.
 */
#import <Foundation/Foundation.h>

@class SFCCredentials;
/*!
 *    @brief Protocol to which autnentication providers must adhere.
 *
 *    Essentially, there is a list of providers and each one is asked for 
 *    credentials in turn, until one provides them.  Each provider may also
 *    provide a means of caching credentials.
 */
@protocol SFCAuthenticationProvider <NSObject>

/*!
 *    @brief Kind of credentials the authenticator provides.
 */
@property (nonatomic, readonly, copy) NSString* kind;

/*!
 *    @brief Make an iterator for the provider.
 *
 *    This method will be invoked just before the first invocation of 
 *    credentialsForRealm:... to obtain an iterator object. The object may be 
 *    anything on which it is valid to do CFRetain/CFRelease.
 *
 *    @return An iterator object.
 */
-(id) makeIterator;

/*!
 *    @brief Supply a set of credentials.
 *
 *    The credentials absolutely must be the correct subclass of SFCCredentials
 *    or an exception will get thrown.
 *
 *    @param realm       Realm to provide credentials for.
 *    @param parameters  Dictionary of parameters that apply to the credentials.
 *    @param iterator    Iterator.  Prior to first use of this method for an
 *                       authentication, -makeIterator will be called to obtain
 *                       this object.
 *           isFirstTime True the first time this is called for a validation,
 *                       False, otherwise.
 *    @param error       If an error occurs and is this is not nil, it will be
 *                       filled in with error info.
 *
 *    @return A set of credentials or nil if it all goes wrong.
 */
-(SFCCredentials*) credentialsForRealm: (NSString*) realm
                            parameters: (NSDictionary*) parameters
                              iterator: (id) iterator
                             firstTime: (bool) isFirstTime
                                 error: (NSError* __autoreleasing*) error;
/*!
 *    @brief Save the set of credentials.
 *
 *    May be invoked after successful authentication to save credentials.
 *
 *    @param credentials Credentials to save.
 *    @param realm       Realm to which credentials apply.
 *    @param parameters  Parameters for the authentication.
 *    @param error       If we fail to save, this will be filled in with error 
 *                       information, unless it is NULL.
 *
 *    @return true if credentials are saved correctly.
 */
-(bool) saveCredentials: (SFCCredentials*) credentials
               forRealm: (NSString*) realm
             parameters: (NSDictionary*) parameters
                  error: (NSError* __autoreleasing*) error;

@end
